Scripting
文档
更新日志
隐私
文档
更新日志
隐私
简体中文

WebView 控制器

WebViewController 是一个用于显示和交互网页内容的控制器。它允许你在脚本中加载 HTML、展示 Web 页面、执行 JavaScript 脚本，并与页面中的 JavaScript 进行消息通信。你可以将它作为浏览器使用，也可以嵌入应用功能页面。

类：WebViewController

1const webView = new WebViewController()

属性

shouldAllowRequest?: (request) => Promise<boolean>

一个可选回调，用于决定是否允许或拦截 WebView 发起的请求。每次加载资源之前都会调用此函数，例如导航到新页面或提交表单时。

适用于拦截跳转行为、自定义安全策略或过滤广告等不需要的请求。

参数

回调函数接收一个 request 对象，包含以下字段：

  • url: string 请求的完整 URL。

  • method: string HTTP 方法，如 GET、POST。

  • body?: Data | null 可选，请求体数据（通常用于 POST 请求）。

  • headers: Record<string, string> 请求头信息。

  • timeoutInterval: number 请求的超时时间（单位为秒）。

  • navigationType: "linkActivated" | "reload" | "backForward" | "formResubmitted" | "formSubmitted" | "other" 触发导航的上下文。

返回值

一个 Promise<boolean>，用于指示是否允许该请求：

  • true：允许请求继续
  • false：阻止该请求

示例

1const webView = new WebViewController()
2
3webView.shouldAllowRequest = async (request) => {
4  console.log('拦截到请求：', request.url)
5
6  // 拦截所有访问 example.com 的请求
7  if (request.url.includes('example.com')) {
8    return false
9  }
10
11  return true
12}
13
14await webView.loadURL('https://www.wikipedia.org')
15await webView.present({ navigationTitle: '已过滤的网页视图' })

方法

loadURL(url: string): Promise<boolean>

加载指定 URL 的网页内容。

  • 参数：

    • url：要加载的网页完整地址。

  • 返回：Promise<boolean> — 加载成功返回 true。

loadHTML(html: string, baseURL?: string): Promise<boolean>

加载原始 HTML 字符串内容。

  • 参数：

    • html：要渲染的 HTML 字符串。
    • baseURL（可选）：用于解析相对路径的基础 URL。

  • 返回：Promise<boolean> — 加载成功返回 true。

loadData(data: Data, mimeType: string, encoding: string, baseURL: string): Promise<boolean>

加载原始数据作为网页内容。

  • 参数：

    • data：要加载的二进制内容。
    • mimeType：内容的 MIME 类型，例如 "text/html"。
    • encoding：字符编码，例如 "utf-8"。
    • baseURL：用于解析相对路径的基础地址。

  • 返回：Promise<boolean>

waitForLoad(): Promise<boolean>

等待 WebView 加载完成。

  • 返回：Promise<boolean>

getHTML(): Promise<string | null>

获取当前页面的 HTML 内容。

  • 返回：Promise<string | null>

evaluateJavaScript<T = any>(javascript: string): Promise<T>

在 WebView 中执行指定的 JavaScript 代码。

  • 参数：

    • javascript：要执行的 JavaScript 代码字符串。若希望返回值，必须在代码中使用 return。

  • 返回：Promise<T> — JavaScript 执行结果将作为 Promise 的值返回。

示例

1const webView = new WebViewController()
2await webView.loadURL("https://example.com")
3const title = await webView.evaluateJavaScript("return document.title")
4console.log(title) // "Example Domain"
5webView.dispose()

或：

1const webView = new WebViewController()
2await webView.loadHTML(`
3  <html>
4    <body>
5      <script>
6        window.myValue = 42
7      </script>
8    </body>
9  </html>
10`)
11
12await webView.waitForLoad()
13
14const result = await webView.evaluateJavaScript('return window.myValue')
15console.log(result) // 42

addScriptMessageHandler<P = any, R = any>(name: string, handler: (params?: P) => R): Promise<void>

添加一个脚本消息处理器，可在网页中通过 JavaScript 调用，并接收原生代码返回的结果。

  • 参数：

    • name：消息处理器名称，必须唯一且非空。
    • handler：处理函数，接收来自网页的参数并返回一个值，作为 Promise 的结果回传给网页。

  • 返回：Promise<void> — 添加成功后完成。

示例

1let webView = new WebViewController()
2
3await webView.addScriptMessageHandler("sayHi", (greeting: string) => {
4  console.log("收到消息", greeting)
5  return "你好！"
6})
7
8await webView.loadHTML(`
9  <html>
10    <body>
11      <script>
12        (async () => {
13          const response = await window.webkit.messageHandlers.sayHi.postMessage("Hi!")
14          alert(response) // 弹出 "你好！"
15        })()
16      </script>
17    </body>
18  </html>
19`)

present(options?: { fullscreen?: boolean, navigationTitle?: string }): Promise<void>

以模态窗口形式展示 WebView。

  • 选项：

    • fullscreen：是否以全屏模式展示。
    • navigationTitle：导航栏标题（可选）。

  • 返回：Promise<void>

canGoBack(): Promise<boolean>

判断 WebView 是否可以后退。

canGoForward(): Promise<boolean>

判断 WebView 是否可以前进。

goBack(): Promise<boolean>

返回上一页。

goForward(): Promise<boolean>

前进到下一页。

reload(): Promise<void>

重新加载当前网页。

dismiss(): void

关闭 WebView 页面（若当前正在展示）。

dispose(): void

释放 WebView 实例并清理资源。

  • 如果 WebView 正在展示，将先自动关闭。
  • 重要：请务必调用此方法以避免内存泄漏。

完整示例

1const webView = new WebViewController()
2
3await webView.addScriptMessageHandler('greet', (name) => {
4  return `你好，${name}`
5})
6
7await webView.loadHTML(`
8  <html>
9    <body>
10      <h1>自定义网页视图</h1>
11      <button onclick="sendMessage()">打招呼</button>
12      <script>
13        async function sendMessage() {
14          const response = await window.webkit.messageHandlers.greet.postMessage("Alice")
15          alert(response)
16        }
17      </script>
18    </body>
19  </html>
20`)
21
22await webView.present({ navigationTitle: '网页视图示例' })
23webView.dispose()
大纲